Collection of Tools & Utilities/Collection of Tools and Utilities.iso/basic/pbc22a.zip/LIB_BI.DOC

Text File | 1992-06-24 | 25KB | 547 lines

     LIB_BI.DOC  Copyright (c) 1992  Daniel M. Smith, Jr.

              TOWARD LIBRARIES AND INCLUDE FILES



This document consists of a basic tutorial on BASIC include
files and libraries. It is included with my libraries by the
kind permission of the author. The text has been edited for
consistency with my existing documentation and includes minor
alterations where I considered them helpful.
   -- Thomas G. Hanlin III

While the following might be considered mundane by experienced
programmers, it's always nice to have a good foundation to
begin building on.  With that in mind, the examples and
discussion of topics will be in relatively layman terminology.
To give you an excellent grasp of each idea presented, examples
and step-by-step procedures will be given.  If you are using
any version of QuickBASIC including QBX Professional
Development System, the information presented here is
applicable to all, although some versions may present specific
problems regarding arguments and syntax. In fact, it is
germaine to all higher level languages but specifically to the
many forms of BASIC which is the language we are concerned
about.

Many routines have been developed by programmers to accomplish
tasks within the BASIC environment. Some are simple, yet others
are extremely complex, possibly requiring memory allocation,
etc. Since these routines are already available why waste time
trying to re-invent the wheel so to speak; include the ones you
require into your program with the $INCLUDE Metacommand (hardly
layman language, so let's take time right now to find out about
this special terminology).

Metacommands are special commands that are used to make your
programs perform in a specific fashion. BASIC has three such
commands; two ($DYNAMIC and $STATIC) which deal with allocation
of dimensioned arrays and the $INCLUDE command which provides a
means of incorporating external programs or routines into your
programs. It specifically tells the compiler to stop processing
the current program in favor of the program directed by the
$INCLUDE Metacommand. When the included program ends, execution
returns to the next line of the main program following the
included routine.

We are only concerned here with $INCLUDE since it is the means
by which all external routines are usually made a part of the
main program. There is a specific syntax required with all
metacommands that needs to be emphasized; most curious is that
these commands are always preceded by REM or the apostrophe
character. The following is the correct syntax for $INCLUDE:

   REM $INCLUDE: 'MyFile.BI'
      or
   ' $INCLUDE: 'MyFile.BI'

More than one metacommand can be placed on the same line as
long as they are separated by white space. The other two
metacommands don't require an argument, so no colon (delimiter)
is required when using them. Note that the above argument is
enclosed by single quotation marks (apostrophes).

What is a ".BI" file?  Nothing can be more frustrating than
trying to figure out what constitutes an include file when you
have never been near one before.  Forget trying to track it
down in reference books!! Here it is in a nutshell and will
save you a lot of time.

First, it doesn't have to have the ".BI" extension at all, but
that's the common extension used for BASIC Include files.
Second, no SUB or FUNCTION programming statements are permitted
in the file; and Third, include files must be in ASCII format.
A ".BI" file then is simply the declaration statements
identifying the external subroutine or function that you want
to be included into the main program. The following syntax is
what you could expect to find in a typical ".BI" file. Let's
call it 'WINDO.BI'.

The metacommand is:
   REM $INCLUDE: 'WINDO.BI'

The contents of the file might be:

   DECLARE SUB Windo (TRow%, LCol%, BRow%, RCol%)
   DECLARE SUB Colour (ForeGrd%, BackGrd%, Scrn%)
   DECLARE SUB Border (Style%, Title$)
   DECLARE SUB WritWin (FC%, BG%, Text$)
   ' (etc)

The list could go on to include other windowing capabilities
such as saving the screen the window pops up on, restoring the
screen when the window is closed, etc.  Whatever the routine or
function you wish to include in your program requires a
definition statement similar to the above in the ".BI" file.
The actual program defined is, of course, located in a library
of subroutines; you are only telling the program to expect
these particular subroutines to be called elsewhere in the
program. If it were not for the ".BI" file and the declarations
contained therein, when the program reached the call to the
subroutine a "SUBPROGRAM NOT DEFINED" error message would be
encountered. Every subroutine and function must be defined
either at the beginning of the main module or in the ".BI" file
if it is to be called during program execution.  I should also
point out here that all arguments (ie., those within the
parentheses in the examples above) must be established in your
program before you make the call to the external subroutine.
The % arguments require integers and $ arguments require
strings.

Let's assume you have a key trapped that directs your program
to a label called WIN. We would expect to find something like
the following:

   WIN:
      TRow% = 8: LCol% = 20: BRow% = 18: RCol% = 60
      BackGrd% = 2: ForeGrd% = 15: Scrn% = 0
      Style% = 1: Title$ = "TEST WINDOW"

Now that the parameters are established:

   Border Style%, Title$
   Colour ForeGrd%, BackGrd%, Scrn%
   Windo TRow%, LCol%, BRow%, RCol%

The parameters can be set when the function is used, for
example:

   LOCATE 10, 25
   WritWin 14, 4, "This is only a test!"

By the way, why use Colour instead of Color, or Windo instead
of Window? Because COLOR and WINDOW are BASIC keywords! We
can't use them, since they are already defined to mean
something else. Sometimes you have to be careful with names.

Declaration is not required for GOSUB, since you never have to
pass any arguments explicitly.  The GOSUB statement is kind of
a specialized version of GOTO, not a subroutine in the sense
that a SUB or FUNCTION is.

Hopefully, this will help you to a proper perspective of ".BI"
files.

NOW!! Here comes the big one. We will step through this very
slowly because libraries are the backbone of programming. Each
time a programmer prepares a method to accomplish a certain
job, it becomes candidate for retention, since the same routine
might be required again (either by himself or other persons who
program in the same language).  These routines are normally
placed in libraries. It could be a small library, or, if many
routines have been created, it could be quite large. The term
"library" is very appropriate, because (like books) routines
can be removed from programming libraries and used when you
need them, but do not need to be kept in your program when you
don't. Much work and research go into solving specific tasks or
coming up with better and more efficient ways of doing a
particular job. Making these great routines available to others
makes programming so much easier because you won't have to
waste time trying to come up with the same routine again. Just
extract it from the provided library and place in a new library
you are going to use. Very easily said, but it takes
considerable doing. This is exactly what we are going to
examine now.

We will step through the entire procedure for creating a new
library exactly in the same order as you should every time you
decide to use someone else's library routines. Please keep in
mind that these instructions are given from a QuickBASIC
viewpoint. With other versions of BASIC you will have to make
substitutions or modifications in the syntax where required.

First you must decide which routines you are going to need from
the library. Make a list of the names of each routine on paper
leaving room on the right for additional information.  You will
realize the advantage of doing this shortly.

Next, you must have a listing (.LST) file of the library to
find ou